home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / ams__l~1.zoo / man / soundenv.man < prev    next >
Encoding:
Text File  |  1993-09-05  |  5.0 KB  |  163 lines
  1.                         ATARI MACHINE SPECIFIC LIBRARY
  2.  
  3.  
  4.  
  5. NAME
  6.      SoundEnvelope
  7.  
  8. SYNOPSIS
  9.      #include <SoundEnvelope.h>
  10.  
  11.      class SoundEnvelope
  12.      short DoSounds()
  13.  
  14. DESCRIPTION
  15.      There are three ways in which an application may produce sound:
  16.         1) XBIOS Dosound - Sound changes every vertical retrace
  17.            2) Giaccess      - Sound changed by the calls
  18.         3) Sample sound  - Sound changes at high frequency
  19.  
  20.      These methods are basicaaly incompatible with each other.
  21.      This module provides high-level support (2), that is similar
  22.      to (1) in operation, but overcomes the single-thread nature
  23.      of Dosound().
  24.  
  25. FUNCTIONS
  26.      short DoSounds()
  27.        Advance any pending sounds.  Returns number of sounds still playing.
  28.  
  29. CLASSES
  30.      Instances of the class SoundEnvelope represent sounds that may occur.
  31.      A given instance may be Started more than once - may even overlap
  32.      the sound of itself Started earlier.
  33.  
  34.      There are two basic types of SoundEnvelope - simple, and plotted.
  35.      A simple envelope just follows linear paths to end.  A plotted
  36.      envelope follows a path determined by an array of (pitch,volume)
  37.      pairs.
  38.  
  39. CLASS MEMBERS
  40.   SoundEnvelope::
  41.      SoundEnvelope(...
  42.  
  43.      void Start()
  44.  
  45. USAGE
  46.  
  47. SEE ALSO
  48.      SoundEnvelope, SampledSound, Dosound (in osbind.h)
  49.  
  50. AUTHOR
  51.      Warwick Allison, 1992.
  52.      warwick@cs.uq.oz.au
  53.  
  54. COPYING
  55.      This functionality is part of the Atari Machine Specific Library,
  56.      and is Copyright 1992 by Warwick W. Allison.
  57.  
  58.      The Atari Machine Specific Library is free and protected under the
  59.      GNU Library General Public License.
  60.  
  61.      You are free to copy and modify these sources, provided you acknowledge
  62.      the origin by retaining this notice, and adhere to the conditions
  63.      described in the GNU LGPL.
  64.                         ATARI MACHINE SPECIFIC LIBRARY
  65.  
  66.  
  67.  
  68. NAME
  69.      Timer
  70.  
  71. SYNOPSIS
  72.      #include <Timer.h>
  73.  
  74.      unsigned long Hz200()
  75.      void Delay(unsigned long msec)
  76.  
  77.      class TimerSpeed
  78.  
  79.      void HaltTimerA()
  80.      void SetTimerA(void ISR(), TimerSpeed&)
  81.      void SetTimerA(void ISR(), int Hz)
  82.  
  83. DESCRIPTION
  84.      There are two basic ways in which a real-time application controls
  85.      the speed at which things occurs.  One is by clocking to the vertical
  86.      retrace signal (see DoubleBuffer), the other is to use one of the
  87.      system hardware timers.
  88.  
  89. FUNCTIONS
  90.      unsigned long Hz200()
  91.        Returns the number of 200ths of a seconds since the computer was
  92.        turned on.
  93.  
  94.      void Delay(unsigned long msec)
  95.        Wait for the given number of milliseconds (accurate to 200ths of
  96.        a seconds).
  97.  
  98.      void HaltTimerA()
  99.        Stop Timer A, the only user-free timer.
  100.  
  101.      void SetTimerA(void ISR(), TimerSpeed&);
  102.        Set Timer A to execute the given INTERRUPT Service Routine at
  103.        the speed given.  NOTE:  A regular C function is NOT sufficient
  104.        to use as an ISR (see USAGE below).
  105.  
  106.      void SetTimerA(void ISR(), int Hz)
  107.        A much slower form of the above.
  108.  
  109. CLASSES
  110.      class TimerSpeed is used to overcome the way timer speeds are defined.
  111.      While it is possible to have timers run at almost any frequency, the
  112.      value to give to the hardware for these frequencies are in terms that
  113.      are not usually useful.  By using the TimerSpeed class, these problems
  114.      can be ignored by the programmer.
  115.  
  116. CLASS MEMBERS
  117.   TimerSpeed::
  118.      TimerSpeed(int Hz)
  119.        Create a timer speed as close as possible to the requested speed.
  120.      operator int()
  121.        Returns the actualy speed of the timer, in Hz.
  122.  
  123. USAGE
  124.      When writing an ISR, the programmer is defining a routine that will
  125.      be executed at each pulse of the timer to which it is attached
  126.      (Timer A).  The routine will need to be written using assembler and
  127.      should have the following form:
  128.  
  129.           _ISR:
  130.               bclr   #5,0xFFFFFA0F    | Reset interrupt-pending signal
  131.               moveml ...,sp@-         | Save any used registers
  132.                ...                    | Whatever processing is needed
  133.               moveml sp@+,...         | Restore any used registers
  134.               rte                     | Return from the interrupt
  135.  
  136.      If an interrupt requires to disable itself, use the following in
  137.      the "Whatever processing is needed" code:
  138.  
  139.               bclr   #5,0xFFFFFA07    | Disable interrupt on timer A
  140.               bclr   #5,0xFFFFFA13    | Clear interrupt mask for timer A
  141.  
  142. SEE ALSO
  143.      SampledSound (uses Timer A for playing sounds)
  144.  
  145. BUGS
  146.      The minimal frequency is 82Hz.
  147.      The maximum frequency is limited by the length of the ISR.
  148.  
  149. AUTHOR
  150.      Warwick Allison, 1992.
  151.      warwick@cs.uq.oz.au
  152.  
  153. COPYING
  154.      This functionality is part of the Atari Machine Specific Library,
  155.      and is Copyright 1992 by Warwick W. Allison.
  156.  
  157.      The Atari Machine Specific Library is free and protected under the
  158.      GNU Library General Public License.
  159.  
  160.      You are free to copy and modify these sources, provided you acknowledge
  161.      the origin by retaining this notice, and adhere to the conditions
  162.      described in the GNU LGPL.
  163.